feat: structured constraints for instruments and beyond by raginpirate · Pull Request #424 · Universal-Commerce-Protocol/ucp

raginpirate · 2026-05-08T10:03:18Z

Prototype revision related to #288
This is heavily AI generated to quickly show the thinking and primitives; do not trust the descriptions or small implementation quirks here!

What

Introduces a single constraint primitive (constraint.json) and applies it consistently across instrument and credential availability. Replaces ad-hoc booleans (requires_card_verification,
billing_address_granularity) with a uniform shape: required_fields[] plus domain-specific custom keys.

New primitives

constraint.json — universal base: required_fields[] of property names + open additionalProperties for domain keys. Every constraint object in UCP follows this shape.
payment_funding_source.json — intermediate credential schema. Concrete funding-source credentials (card_credential, network_token_credential) inherit from it; consumers detect funding sources by ancestry, not
annotation.
address_constraint.json — constraint-shaped, required_fields scoped to postal_address.json properties. Reusable across payments and fulfillment.
credential_constraint.json — { type, constraints } entry. Single primitive used on both axes below.

Reshaped

Card credentials split by verification scheme, not by PAN flavor.
- card_credential.json carries cvc. Used whenever the verification is a CVC, regardless of whether number is an FPAN, network token, or wallet token.
- network_token_credential.json (new) carries cryptogram + eci_value as schema-required. Used whenever the verification is cryptographic.
- The card_number_type discriminator goes away — verification fields define the type.
available_card_payment_instrument.constraints exposes four top-level keys:
- required_fields — names instrument properties that MUST be present (e.g. billing_address).
- brands — accepted card brands (instrument-level; brand isn't a credential field).
- billing_address — address_constraint describing what address fields must be populated.
- credentials[] / funding_sources[] — same credential_constraint primitive on two orthogonal axes. credentials constrains the wire shape the handler ingests; funding_sources constrains the underlying instrument
  behind the wire credential. Constraints sit on the semantically correct axis only — never duplicated.

Cross-domain reuse

fulfillment_available_method.json adopts the same primitives — top-level constraints extending constraint.json, with destination reusing address_constraint.json. Closes the address-constraint gap on the
fulfillment side without inventing parallel concepts.

Example

  {
    "type": "card",
    "constraints": {
      "required_fields": ["billing_address"],
      "brands": ["visa", "mastercard"],
      "billing_address": {
        "required_fields": ["postal_code", "address_country"]
      },
      "credentials": [
        { "type": "token", "constraints": { "token_provider": ["dev.shopify.spt"] } }
      ],
      "funding_sources": [
        { "type": "card",          "constraints": { "required_fields": ["cvc"] } },
        { "type": "network_token" }
      ]
    }
  }

Reads as: handler accepts a token credential on the wire, conveying either a CVC-verified card or a cryptogram-verified network token. Merchant requires CVC on raw cards, requires a billing address with at least
postal code + country, and accepts visa/mastercard.

jamesandersen

@raginpirate thanks for putting #424 together — I do think this proposal works well:

(+) Introduces a new credential type network_token
- Adds the distinction I was looking for originally in #296 ;-)
- ... and probably will have implications for the doc changes proposed in #367
(+) Required fields are explicit via the new constraint primitive
- e.g. under instrument -> credentials -> constraints -> required_fields (more like where #288 started but now implemented at the right level)
- In contrast to where #288 was trending with implicit constraints via instrument -> constraints -> requires_card_verification and docs to explain intent at the credential level
(+) Cross-domain reuse e.g. address_constraint.json, credential_constraint.json
(-) Breaking change with removal of card_number_type ... left separate comment on this

On the "credential inception" point e.g. distinct constraint on a wire credential and - where applicable - the funding source underlying it. What do you think about taking this on in a separate PR? I'd like to better understand if there is a concrete scenario requiring both? e.g. can a business require a CVV on the underlying instrument while only accepting the network token? It's been a winding road so far to get alignment on updated constraint modeling for just the "wire credential" ... hopefully a follow-on for the underlying funding source could be quicker and cleaner after landing this.

TBH ... it took a while to grok this all (in large part for lack of good focus time) but I think the resolved examples are actually much easier than the schema suggests at first glance - just as another sanity check the multiple entries under credentials is how we address the hurdle that led us to the implicit bool and AVS enum on #288. Look right?

  {                                                                                                                            
    "available_instruments": [                              
      {                                                                                                                        
        "type": "card",  // card-based instrument                                                                                         
        "constraints": {                                                                               
          "brands": ["visa", "mastercard"],                                                                                    
          "required_fields": ["billing_address"],                                                                     
          "billing_address": {                                                                                                 
            "required_fields": ["postal_code"] // e.g. AVS1, but adapts to other schemes                                                                    
          },                                                                                                                   
          "credentials": [
            { 
              "type": "card", // FPAN
              "constraints": { "required_fields": ["cvc"] } 
            },
            { 
              "type": "network_token", // DPAN / CPAN
              "constraints": { "required_fields": ["cryptogram"] } // could add ECI if a business needs it
            }
          ]                                                                                                                    
        }                                                   
      },                                                                                                                        
    ]                                                                                                                          
  }

jamesandersen · 2026-05-18T22:44:54Z

          "const": "card",
-          "description": "The credential type identifier for card credentials."
-        },
-        "card_number_type": {


Should we deprecate rather than removing to avoid a breaking change?

jamesandersen · 2026-05-18T22:46:20Z

+        },
+        "cryptogram": {
+          "type": "string",
+          "description": "Per-transaction cryptogram. Structurally required — a network token credential without a cryptogram is a CVC-verified card; submit it as `card_credential` instead."


nit: Could we indicate this may be either long form or short form (e.g. dCVV)

jamesandersen · 2026-05-18T22:47:43Z

+    {
+      "type": "object",
+      "required": ["type", "number", "cryptogram", "eci_value"],
+      "properties": {


Thoughts about adding token_requestor_id (#296) onto network_token_credential while we're at it? not widely used as discussed on that PR but we do have the Braintree BYOT example

jamesandersen · 2026-05-18T22:47:56Z

@@ -0,0 +1,61 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://ucp.dev/schemas/shopping/types/network_token_credential.json",


This scratches that itch I had from #296 ;-)

TateLyman · 2026-05-22T00:42:41Z

Schema read only.

One validation gap to keep an eye on if this moves from prototype to spec shape: credential_constraint.json describes constraints as being scoped to the named credential type, and the concrete credential schemas define narrowed $defs.constraint objects, but the actual reference is still the generic base constraint:

"constraints": {
  "$ref": "constraint.json"
}

Because of that, JSON Schema validation will not use type to select card_credential.json#/$defs/constraint or network_token_credential.json#/$defs/constraint. For example, these look invalid by the intended semantics but appear valid against the current primitive:

{ "type": "card", "constraints": { "required_fields": ["cryptogram"] } }
{ "type": "network_token", "constraints": { "required_fields": ["cvc"] } }

Same issue for funding_sources: the body says entries must reference schemas inheriting from payment_funding_source.json, but type is an unconstrained string in the schema itself.

Suggested direction: either make credential_constraint an explicit oneOf over known credential types (if type == card then constraints -> card_credential#/$defs/constraint, etc.), or keep it intentionally registry/runtime-validated and soften the schema language so platforms do not assume this is machine-checkable from the JSON Schema alone.

The interoperability risk is that merchants/platforms may think constraint payloads are statically validated, while cross-axis mistakes only exist in prose. That matters for checkout because a mistyped funding-source requirement can become a failed tokenization/payment path rather than a schema error.

ready example

1fa04e8

raginpirate mentioned this pull request May 8, 2026

feat: add card verification and billing address constraints #288

Open

10 tasks

kmcduffie added the payments label May 11, 2026

jingyli added the WIP label May 13, 2026

jamesandersen reviewed May 18, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: structured constraints for instruments and beyond#424

feat: structured constraints for instruments and beyond#424
raginpirate wants to merge 1 commit into
mainfrom
proto/funding-source-and-credential-constraints

raginpirate commented May 8, 2026 •

edited

Loading

Uh oh!

jamesandersen left a comment

Uh oh!

jamesandersen May 18, 2026

Uh oh!

jamesandersen May 18, 2026

Uh oh!

jamesandersen May 18, 2026

Uh oh!

jamesandersen May 18, 2026

Uh oh!

TateLyman commented May 22, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

Conversation

raginpirate commented May 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What

New primitives

Reshaped

Cross-domain reuse

Example

Uh oh!

jamesandersen left a comment

Choose a reason for hiding this comment

Uh oh!

jamesandersen May 18, 2026

Choose a reason for hiding this comment

Uh oh!

jamesandersen May 18, 2026

Choose a reason for hiding this comment

Uh oh!

jamesandersen May 18, 2026

Choose a reason for hiding this comment

Uh oh!

jamesandersen May 18, 2026

Choose a reason for hiding this comment

Uh oh!

TateLyman commented May 22, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

raginpirate commented May 8, 2026 •

edited

Loading